Introducing OpenSpartan Forerunner - A MCP Server For Halo Infinite

It’s been a while since I talked about a Halo hobby project of mine - bit of a whirlwind start of the year. Being more immersed in AI-based work and especially with the emergence of Model Context Protocol (MCP), I thought that this would be a great opportunity to build on the work that I’ve done with my Halo Infinite REST API wrapper (Grunt, in case you missed it).

If you haven’t spotted a trend¹ yet, I am all about finding novel ways to quickly analyze my Halo performance. I’ve been doing this long enough² that when a new opportunity popped up to merge Halo Infinite data with some AI sprinkled for good measure, I decided to invest some time this past weekend and build out a working MCP server that allows anyone to access their Halo Infinite data from whatever MCP client they are using, like Visual Studio Code, Claude Desktop, or Cursor (list not exhaustive, of course).

Forerunner - your in-LLM Halo Infinite assistant #

The beautiful thing about Halo Infinite is that it has an extensive and extremely mature REST API surface. I’ve already integrated deeply with it when I built OpenSpartan Workshop for local match analysis on Windows.

For the past year, I’ve been relying more and more on being more productive³ with the help of Large Language Models (LLMs), and I kept asking myself - can I just get my Halo data inside the LLM client as I work there? As it turns out, I can!

The recipe for getting the data inside the LLM client is, of course, a MCP server built exactly for this purpose. Think of an MCP server as a standard API plug-in that extends existing LLM clients (that support MCP) to give them access to other data that the model might not know about.

In my case, the LLMs I am using know absolutely nothing about my Halo match performance or things like my current armor configuration. You know - the things that I see in the game.

Enter Forerunner - an entirely local MCP server that effectively has access to the entire Halo Infinite REST API service through my .NET wrapper for it, Grunt.

Connecting Forerunner to your MCP client #

To get started, you will need to first install the .NET Runtime. Forerunner is written in C# and uses brand-spanking new .NET MCP SDK, and can run on any platform that supports .NET - Windows, macOS, and even Linux.

With the runtime on your box, download the latest release of Forerunner from the GitHub repository. Extract it in a location that you prefer.

Why not just provide an installer? That way someone that wants to use the MCP server won’t need to download ZIPs and deal with extracting them locally.

Great question! Because Forerunner is still in the early alpha stages, I thought it would be easier (and quicker) to iterate without a heavyhanded approach, that is - installing things. I want to be very transparent about what’s in the package (the release ZIP) so that those that want to try and experiment with the server have maximum flexibility. Once I stabilize it a bit more, I will have a more… stable way to distribute the binaries.

Oh, and before I forget - you will need the .NET 9 SDK installed on your machine before you go any further. Anyway, with the ZIP extracted, it’s time to configure your MCP client!

Visual Studio Code #

In Visual Studio Code, you will need to open the Settings first.

Then, we’re going to switch to JSON mode:

There, at the root level add a new mcp node, like this (where the path to the EXE can be inferred from the location where you extracted the ZIP):

"mcp": {
    "inputs": [],
    "servers": {
        "mcp-halo-infinite": {
            "command": "PATH_TO_YOUR_OpenSpartan.Forerunner.MCP.exe",
            "args": [],
            "env": {}
        }
    }
}

Once you set this up, you will notice a Start button pop up above the server definition. Click on that to start it.

You will need to open GitHub Copilot in Visual Studio code and switch it to Agent mode.

Claude Desktop #

For Claude Desktop, the process is somewhat similar. Go to the menu, the File, and then - Settings:

From there, go to Developer and use Edit Config to edit the application configuration (your screen will be a bit different if you have not added any MCP servers, but the idea is the same):

You will get the File Explorer (or some other tool, if you are not on Windows) with the file in sight - claude_desktop_config.json (extension may be hidden):

You can open that file and add the following configuration to the root of the JSON file:

"mcpServers": {
    "mcp-halo-infinite": {
        "command": "PATH_TO_YOUR_OpenSpartan.Forerunner.MCP.exe",
        "args": [],
        "env": {}
    }
}

Similar enough to Visual Studio Code? I think so. Once you set the configuration, make sure that you fully quit Claude Desktop (e.g., from the system tray in Windows) for it to pick up the changes.

Once you restart Claude Desktop, you should see the tools highlighted in the chat box!

Everything that starts with opsp_ (stands for OpenSpartan) is related to Forerunner.

Testing Forerunner #

It’s now time for the exciting part of the blog post - you’ve done the hard work of downloading and configuring Forerunner on your machine. Let’s now try and use it to get some data.

Authentication #

Before you get started, you will need to log in with your Microsoft Account (MSA) that you use for your Halo play time. The good news is that the moment you enable Forerunner in your MCP client, you will be prompted to sign in. Forerunner supports two modes of getting to the account - plain and broker-based.

If you use the plain authentication method, you can just use Forerunner in the standard configuration that I’ve outlined above. What that means is that when you get prompted for credentials through your default web browser. It’s a good way to go if you don’t want to connect your MSA to Windows, or if you are running on a platform that is not Windows.

The alternative is using an authentication broker (only Windows is supported at this time). This will allow Forerunner to use one of the MSAs that you’ve connected to Windows. This functionality is coming soon!

Before we go any further, I think it’s important to call out that you’re using this MCP server at your own risk. While any of the OpenSpartan tools do not abuse or misuse any of the Halo Infinite or Xbox REST APIs, I cannot guarantee that your account will not be temporarily or permanently banned as a result of the use of this application.

Indeed, that’s a good reminder! This is not an official Microsoft/Halo Studios or Microsoft/Halo Studios-endorsed product. I love tinkering with the APIs and so far haven’t had any issues, but this is not a guarantee of future support or availability.

Asking questions #

To try Forerunner, here are some questions you can ask⁴:

1. What are my latest stats for matchmade games?
2. What were the outcomes for my last 10 matches?
3. What is my current armor configuration?
4. What’s currently available on sale through The Exchange?
5. What’s my current career rank?

I am actively working on integrating more and more of Grunt into the MCP implementation so that you can answer more questions and get more of your Halo Infinite data where you use your LLM of choice. And with OpenAI supporting MCP⁵, this will become even more powerful as you can leverage their models with your Halo Infinite data.

Here is what that might look like in action:

If you like getting stats quickly, this is the way to go!

Image support #

One of the more fun aspects of Forerunner that I implemented is its ability to return images. For example, when you are asking it for your gear configuration, it provides the images for all the gear you have equipped. The unfortunate part is that there is a lot of data to return so Claude Desktop doesn’t quite light it up, and other MCP clients don’t support (yet) image rendering. However, you can see what it could look like you if you go down MCP Inspector route.

As client support gets better, I expect this functionality to “just work” once you add the server.

What’s ahead #

The code you see implemented in Forerunner right now just scratches the surface of the things that Grunt enables. I am excited to keep evolving it a bit more and making more Halo Infinite data easily accessible for analysis through your LLM of choice. And OpenSpartan Workshop will continue to get better too, of course, since it uses the same library under the hood.

I am looking at also having a deeper integration with HCS data, so if you are someone who watches pro matches closely, I’d love to hear your thoughts on how I can make Forerunner useful for you.

Last but not least, if you are developer, I would also encourage you to start building your MCP clients and servers using the .NET SDK - using it to build Forerunner was a delightful experience.